home *** CD-ROM | disk | FTP | other *** search
/ 3D Images / 3D Images.iso / programs / amiga / genesis / usingflexiparse < prev    next >
Text File  |  1995-02-09  |  15KB  |  502 lines
  1. Spikey Boy!!
  2.  
  3.      Here it is, a sort of 'beta quardruple minus' version of the infamous
  4. FLEXIPARSE solid-modelling interpreter/parser!
  5.      Right, lets get down to the buisness with regards how to use it, what
  6. it can do and what it can't do!
  7.      Firstly, lets get the 'How to use it bit' out the way. The parser is
  8. invoked with the command:
  9.                             1> flexiparse
  10. from the CLI.
  11. You shall then be confronted with some copyright crap and a MODULA-2 input
  12. file request:
  13.                             in> <filename>.csg
  14.  
  15. At the above request, you should type the filename followed by a .csg
  16. extension. The CSG definition file for the model is then read in,
  17. syntactically analysed, lexically analysed and finally code is generated in
  18. your format (assuming you have no errors!!). Before the code-generation
  19. phase is initiated, another requestor will appear:
  20.  
  21.                             out> <filename>
  22.  
  23. which will request you to type the name of the file to put the code that has
  24. been generated in your format.
  25. I've currently got a version of FLEXIPARSE lying on my desk that will do all
  26. the above input file/output file stuff without requesting you to type the
  27. names of the files in. That is, you can type: 1> flexiparse greektemple.csg
  28. and it will automatically produce a greektemple.model file in your format
  29. and dump it to disk. I'll send you this when I've added some more features
  30. and thoroughly tested it!
  31.  
  32. Anyway, you can then GENESIS the resulting model file. Make sure you've
  33. opened a screen first, as FLEXIPARSE doesn't automatically write an open
  34. screen command to the output file.
  35.  
  36. Its probably, a good idea to incrementally test FlexiParse by doing simple
  37. objects first and then getting more complex. I realise there are some bugs
  38. in the program of which the known ones are documented at the end of this
  39. file.
  40.        Good Luck! You'll need it...
  41.  
  42. FLEXIPARSE .CSG FILE FORMAT
  43. ===========================
  44.  
  45.  
  46. FlexiParse basically accepts standard WINSOM model files with regards
  47. overall syntactic structure. Briefly, this is explained below:
  48.  
  49. PRIMATIVES
  50. ----------
  51.  
  52.     Primatives have the following syntax:
  53.  
  54.             <Prim_Name> (<Argument1>,<Argument2>,...<ArgumentN>)
  55.  
  56.             e.g. PLANE(0,1,0)
  57.  
  58.     Remember, all arguments are seperated by commas.
  59.     The only exception to this is for primatives that don't take any
  60. arguments e.g. EMPTY which does not need any brackets
  61.  
  62.             e.g. EMPTY
  63.  
  64.     All the primatives implemented on the version of GENESIS you last gave
  65. me have been implemented in FlexiParse.
  66.  
  67. TRANSFORMS
  68. ----------
  69.  
  70.     As per WINSOM format, Transforms can be used after primatives, macros or
  71. expressions surrounded by parentheses.
  72.  
  73.     e.g.
  74.           SPHERE(30) XROT(90)
  75.  
  76.           or
  77.  
  78.           DubiousLookingSausageShape XROT(180)
  79.  
  80.           (Assuming DubiousLookingSausageShape has been defined as a macro)
  81.  
  82.           or
  83.  
  84.           (SPHERE(10) UNION SPHERE(20) AT(10,10,10)) YROT(270)
  85.  
  86.  
  87. Finally, like WINSOM, there is no restriction on how many transforms can be
  88. 'chained' together in an expression:
  89.  
  90.          e.g.
  91.               SPHERE(10) XROT(20) YROT(30) ZROT(40) SCALE(3) AT(10,10,10)
  92.  
  93. All the transforms that have been implemented in the version of GENESIS that
  94. you gave me have been implemented in FlexiParse.
  95.  
  96. CSG OPERATORS
  97. -------------
  98.  
  99.      As per WINSOM format. CSG Operators can join primitives, macros and
  100. complex expressions. FlexiParse supports the keywords:
  101.  
  102.      UNION  - Union
  103.      DIFF   - Difference
  104.      INT    - Intersection
  105.  
  106.      e.g.
  107.  
  108.           SPHERE(10) UNION SPHERE(20)
  109.  
  110.           SPHERE(10) DIFF BigLongDanglyObject
  111.  
  112.           (SPHERE(10) UNION SPHERE(20)) DIFF SPHERE(40) UNION (PLANE(0,1,0)
  113.            AT (20,20,20))
  114.  
  115. USE OF PARENTHESES
  116. ------------------
  117.  
  118.      Like WINSOM, the priority of evaluation of expressions can be increased
  119. by the dudicious use of the good old parentheses symbols:
  120.  
  121.                  (......)
  122.  
  123.      e.g. This is performed in the below example to UNION the two SPHEREs
  124. together BEFORE being chopped by the half-plane.
  125.  
  126.           ( SPHERE(10) UNION SPHERE(10) AT(10,0,0) ) DIFF PLANE(0,1,0)
  127.  
  128. COMMENTS
  129. --------
  130.  
  131.     Comments can be easily incorporated in the file by using my favourite
  132. symbol: # (boy, I get so exited when I type it in!!)
  133.     The '#' symbol must surround the area to be commented:
  134.  
  135. e.g.
  136.       # Andy's Amazing FlexiParse Example! #
  137.  
  138.       DRAW SPHERE(10) UNION SPHERE(10) AT(20,0,0);
  139.  
  140.  
  141.     This is quite useful for 'commenting' out bits of a model file during
  142. development of a complex object! (Who says I don't put useful facilities in
  143. my programs!!)
  144.  
  145.  
  146. MACROS
  147. ------
  148.  
  149.     Macro's provide the main power behind the flexiparse environment. They
  150. work similarly to the way that WINSOM macros function, with one small
  151. difference. WINSOM macros 'IMPLICITLY' assume that the macro is evaluated
  152. when it is called:
  153.  
  154.     e.g.  /* A WINSOM program */
  155.  
  156.           TWOSPHERES = SPHERE(10) UNION SPHERE(10) AT (10,0,0);
  157.  
  158.           DRAW SPHERE(1) UNION TWOSPHERES UNION SPHERE(3);
  159.  
  160.      In this example TWOSPHERES will be evaluated as if it were surrounded
  161. by parentheses.
  162.      This is just the way FlexiParse works but for the fact the brackets
  163. must surround the whole macro-definition:
  164.  
  165.      e.g.  # A much better way of doing things using flexiparse #
  166.  
  167.            OBJECT = (SPHERE(10) UNION SPHERE(10) AT(10,0,0));
  168.  
  169.            DRAW SPHERE(1) UNION OBJECT UNION SPHERE(3);
  170.  
  171.  
  172.                     or alternatively,
  173.  
  174.  
  175.            OBJECT = SPHERE(10) UNION SPHERE(10) AT(10,0,0);
  176.  
  177.            DRAW SPHERE(1) UNION (OBJECT) UNION SPHERE(3);
  178.                                    ^
  179.                                    |
  180.                Macro call can alternatively be surrounded by
  181.                                 brackets
  182.  
  183. I feel that this way of defining macros is a bit more consistent, adds a bit
  184. more flexibility and is easier to program and write good code!!
  185.  
  186. Also, macros can be nested within other macros to as many levels as you
  187. like. (Good stuff eh!!)
  188.  
  189.  
  190. STRUCTURE
  191. ---------
  192.  
  193.        The structure roughly obeys the WINSOM file format:
  194.  
  195.  
  196.   Main Body Structure
  197.   -------------------
  198.  
  199.        DRAW <Main Body> ;
  200.        .
  201.  
  202.        The semi-colon and terminating full-stop must be included.
  203.  
  204.   Macros
  205.   ------
  206.  
  207.        <Name> = <Macro Body> ;
  208.  
  209.        The macro is terminated with a semi-colon.
  210.  
  211.  
  212.  
  213.   Thats about it really!!!..
  214.  
  215.  
  216. ERROR DETECTION
  217. ---------------
  218.  
  219.       Probably, the most stable element in the system is the actual parser
  220. which is used to analyse whether or not you've typed in a complete pile of
  221. crap or a solid-modelling masterpiece!! There is one small problem at the
  222. moment in that FlexiParse will tell you that you've got an error but won't
  223. tell you where it is!!
  224.  
  225.       e.g. # An Amateurs solid modelling attempt #
  226.  
  227.            DRAW SPHERE(10) UNION ;
  228.  
  229.            Obviously wrong as the sphere is being UNION'ed with nothing!
  230.  
  231.       Flexiparse will respond with:
  232.  
  233.            You have a Lexical Error Somewhere!!
  234.  
  235.       Hmmm, A bit better than it not telling you I suppose!!
  236.  
  237.       This will be updated soon (promise!!).
  238.  
  239.  
  240.  
  241.  Right, lets now discuss the bad news with regards using FlexiParse:
  242.  
  243.  
  244.  1) Macro Names
  245.     -----------
  246.  
  247.          (i)  Macro Names must be less than 10 Characters Long.
  248.          (ii) Macro Names must not start with a subset of other macro names
  249.               or reserved words
  250.  
  251.               e.g. MAC = SPHERE(3) UNION SPHERE(4);
  252.                    MACSMACRO = SPHERE(10) UNION PLANE(0,1,0);
  253.  
  254.               would cause MACSMACRO to be interpreted as MAC.
  255.               Naughty stuff!! But A Low priority bug-fix at the mo.
  256.  
  257.  
  258.  2) Macro Bodies
  259.     ------------
  260.  
  261.          Hmmm, this is probably the worst problem associated with FlexiParse
  262. to date. The FlexiParse code-generator module often gets slightly confused
  263. when the end of the macro is encountered and will often ignore any
  264. transforms after an invocation of a macro.
  265.          e.g.
  266.  
  267.              OHSHIT = SPHERE(10) UNION SPHERE(10) AT (10,0,0);
  268.  
  269.              DRAW SPHERE(10) UNION PLANE(0,1,0) XROT(20) UNION
  270.                   (OHSHIT) XROT(90) YROT(45);
  271.                             ^        ^
  272.                             |        |
  273.  
  274.                      These would be ignored and would not appear in the
  275.                      output file!! (Extremely Naughty!)
  276.  
  277.          To circumvent this, (Hurrah!!) if you add a dummy EMPTY at the end
  278. of the macro definition, things seem to work!!
  279.  
  280.             e.g.
  281.  
  282.               OHSHIT = SPHERE(10) UNION SPHERE(10) AT (10,0,0) UNION EMPTY;
  283.  
  284.           This is a High Priority bug-fix and depresses me totally as its
  285. quite a difficult bug to fix. It might even facilitate the re-design of the
  286. code-generator module.
  287.  
  288.          Another thing you should not try is to call a macro from its own
  289. definition:
  290.              e.g.  YETAGAIN =  SPHERE UNION (YETAGAIN);
  291.  
  292.          You could be waiting a long time for this one to finish...
  293.  
  294. 3)  Program Size
  295.     ------------
  296.  
  297.           You might have noticed that flexiparse is quite a LARGE executable
  298. file. This is due to a large chunk of Statically allocated memory being
  299. reserved at compile time i.e. I'm using Arrays. The compiled code for the
  300. program (neglecting Arrays,Variables etc..) is just over 17k and this should
  301. not really go over 20k when my modifications have been made. In additions
  302. this shall also then have all data-structures dynamically allocated!!
  303.  
  304. 4) The Insidious Bastard Bug
  305.    -------------------------
  306.  
  307.           The 'Insidious Bastard Bug' is quite odd and I'm not sure if it
  308. really exists or is a bug at all!! The problem seems to lie with an
  309. exception condition that occurs during code-generation and then **StRaNgE**
  310. things start to happen e.g. Produces the wrong output when GENESISED.
  311.           This has only happened to me once and is likely to only happen
  312. when using MACRO's. If you try out any files that don't work or produce the
  313. wrong output then send them to me, in a stamped addressed envelope!!
  314.  
  315. 5) The DRAW SPHERE(10) Bug
  316.    -----------------------
  317.  
  318.          Flexiparse will not allow you to DRAW single primitives:
  319.  
  320.          e.g.  DRAW SPHERE(10);
  321.  
  322.          It will probably come back with the FlexiParse Diagnostic message:
  323.  
  324.          Synchronisation Error..
  325.  
  326.          Although, as with most flexiparse bugs, it can be resolved with the
  327. good old EMPTY statement:
  328.  
  329.                DRAW SPHERE(10) UNION EMPTY;
  330.  
  331.  
  332.  
  333. This is probably all the bugs/bad-points I can think of at the moment.
  334.  
  335.  
  336. THINGS REMAINING TO BE DUN
  337. ==========================
  338.  
  339.  
  340.      Well, there are a fair number of things:
  341.  
  342.  
  343. 1) Making Code-Generator Stable
  344.    ----------------------------
  345.  
  346.    This might require a complete rewrite of this module in order to make it
  347. more efficient and to make it more robust.
  348.  
  349. 2) Dynamic Allocation
  350.    ------------------
  351.  
  352.    A primary goal is to make all structures in FlexiParse dynamic. At the
  353. moment 80% of them are, and they are very efficient in terms of memory
  354. allocation/disposal.
  355.  
  356. 3) Error Handler
  357.    -------------
  358.  
  359.    It would be nice to have one wouldn't it ??  I mean, one that just
  360. doesn't say if an error occurs but also pin-points it visually and also
  361. comes up with a witty message or something!!
  362.  
  363.    e.g. DRAW SPHERE(5) UNION   ;
  364.                              ^
  365.                   Flexi-Error #5 : Primitive/Expression/Macro Expected.
  366.  
  367. Optional Features I'd like incorporated:
  368.  
  369. 4) Library Facilities
  370.    ------------------
  371.  
  372.    Yup, we've discussed this before. A major ability to IMPORT
  373. macro's/objects from on-line disk libraries will be a great facility!
  374.  
  375.   e.g.
  376.  
  377.       GREEKTEMPLE = architecture/greektemple.csg
  378.  
  379. 5) Constants
  380.    ---------
  381.  
  382.    I think the ability to define constants inside a CSG description file
  383. would be most useful:
  384.  
  385.    e.g.
  386.  
  387.         ScaleFactor = 2;
  388.  
  389.         DRAW ( SPHERE(10) UNION SPHERE(10) AT (20,0,0) ) SCALE(ScaleFactor);
  390.  
  391.    This would increase the functionality of the parser almost to the stage
  392. of a CSG language (e.g. ESME) without actually being one!!
  393.    What do you think??
  394.  
  395.  
  396.  
  397. FINALLY
  398. =======
  399.  
  400.    The major problems I foresee at the moment are:
  401.  
  402.        1)  Time
  403.        2)  My Current State of Mind
  404.  
  405.    I'm currently inundated with work at the moment which really pisses me
  406. off as I can't do much on FlexiParse. Also, this leads to depression which
  407. means that even when I do start doing some flexiparsing I feel guilty that
  408. I'm not doing any work. This leads to me doing some work and feeling
  409. depressed....(and so on!!).
  410.    It would be nice to know some reasonable time-scales in order to plan
  411. around my work schedule.
  412.  
  413.  
  414. MISCELLANEOUS
  415. =============
  416.  
  417.    I've recently applied to do the prestigious MA Computing in Design course
  418. at Middlesex Poly after I finish my degree. This is a really brilliant
  419. course and mixes computer-graphics, computer-animation , paintbox and
  420. production skills. So if/when we team up to form our mega-company then I
  421. think the skills I've picked up on this course will be an asset if we ever
  422. decide to branch out to commercial animation etc..
  423.    Anyway, my final-year project is 'crawling' along. My specification is
  424. now to design a surface-modeller for the graphic design department. The
  425. skills I pick up during the project will be useful if we ever decide to
  426. produce surface-modellers etc.. If you have any tips or good books on the
  427. subject, then let me know. Also, do you know any good hidden-line removal
  428. algorithms???
  429.    Also, It would be quite nice if you could send me some info regarding
  430. which libraries/procs to import in order to set up screens,plot-points,
  431. draw-lines etc. using the Benchmark Compiler. The RKM is particullarly vague
  432. in places and I'm a lazy git so I can't be bothered reading it in order to
  433. find out the system calls!! I realise you can either use the Rasters Module
  434. or do it through Intuition. The easiest method would be great, as I'm
  435. currently going through a bought of dyslexia! Anyway, the reason I need them
  436. is to experiment on the Amiga with regards the surface-modeller I'm working
  437. on!
  438.  
  439.    I hope you think FlexiParse is at least Average and at the best quite
  440. good, will hindsight I think if I had to start from scratch I would have
  441. done things a bit differently!! At least you have an interface to the
  442. modeller that is about 200% better than the original one!
  443.    Finally, give me a ring once you've had a bash at using it and if you
  444. find any bugs (which you probably will!) then write 'em down and send them
  445. to me! I have included some example .csg files on the disk which might be
  446. useful!
  447.  
  448.         Have Fun,
  449.  
  450.                   Mc
  451.                               10/12/89
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480. P.S. Have a Happy Crimble!! (Yo Ho Ho and all that rubbish!)
  481.    
  482.  
  483.  
  484.         
  485.  
  486.  
  487.     
  488.  
  489.  
  490.      
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.